<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Healthcheck library for OpenResty</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>lua-resty-healthcheck</h1>



<h2>Contents</h2>
<ul>
<li><a href="#Synopsis">Synopsis </a></li>
<li><a href="#Description">Description </a></li>
<li><a href="#History">History </a></li>
<li><a href="#Copyright_and_License">Copyright and License </a></li>
</ul>


<h2>Topics</h2>
<ul class="">
  <li><strong>README</strong></li>
</ul>
<h2>Modules</h2>
<ul class="nowrap">
  <li><a href="../index.html">resty.healthcheck</a></li>
</ul>

</div>

<div id="content">


<h1>lua-resty-healthcheck</h1>

<p><img src="https://img.shields.io/github/v/tag/Kong/lua-resty-healthcheck?sort=semver" alt="latest version"/>
<img src="https://img.shields.io/luarocks/v/kong/lua-resty-healthcheck?style=flat-square" alt="latest luarocks version"/>
<img src="https://github.com/Kong/lua-resty-healthcheck/actions/workflows/latest_os.yml/badge.svg" alt="master branch"/>
<img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square" alt="License"/>
<img src="https://img.shields.io/twitter/follow/thekonginc?style=social" alt="Twitter Follow"/></p>

<p>A health check library for OpenResty.</p>

<p><a name="Synopsis"></a></p>
<h2>Synopsis</h2>


<pre>
<span class="function-name">http</span> {
    lua_shared_dict test_shm <span class="number">8</span>m;
    lua_shared_dict my_worker_events <span class="number">8</span>m;
    <span class="function-name">init_worker_by_lua_block</span> {

        <span class="keyword">local</span> we = <span class="global">require</span> <span class="string">"resty.worker.events"</span>
        <span class="keyword">local</span> ok, err = we.<span class="function-name">configure</span>({
            shm = <span class="string">"my_worker_events"</span>,
            interval = <span class="number">0.1</span>
        })
        <span class="keyword">if</span> <span class="keyword">not</span> ok <span class="keyword">then</span>
            ngx.<span class="function-name">log</span>(ngx.ERR, <span class="string">"failed to configure worker events: "</span>, err)
            <span class="keyword">return</span>
        <span class="keyword">end</span>

        <span class="keyword">local</span> healthcheck = <span class="global">require</span>(<span class="string">"resty.healthcheck"</span>)
        <span class="keyword">local</span> checker = healthcheck.<span class="function-name">new</span>({
            name = <span class="string">"testing"</span>,
            shm_name = <span class="string">"test_shm"</span>,
            checks = {
                active = {
                    <span class="global">type</span> = <span class="string">"https"</span>,
                    http_path = <span class="string">"/status"</span>,
                    healthy  = {
                        interval = <span class="number">2</span>,
                        successes = <span class="number">1</span>,
                    },
                    unhealthy  = {
                        interval = <span class="number">1</span>,
                        http_failures = <span class="number">2</span>,
                    }
                },
            }
        })

        <span class="keyword">local</span> ok, err = checker:<span class="function-name">add_target</span>(<span class="string">"127.0.0.1"</span>, <span class="number">8080</span>, <span class="string">"example.com"</span>, <span class="keyword">false</span>)

        <span class="keyword">local</span> handler = <span class="keyword">function</span>(target, eventname, sourcename, pid)
            ngx.<span class="function-name">log</span>(ngx.DEBUG,<span class="string">"Event from: "</span>, sourcename)
            <span class="keyword">if</span> eventname == checker.events.remove
                <span class="comment">-- a target was removed
</span>                ngx.<span class="function-name">log</span>(ngx.DEBUG,<span class="string">"Target removed: "</span>,
                    target.ip, <span class="string">":"</span>, target.port, <span class="string">" "</span>, target.hostname)
            <span class="keyword">elseif</span> eventname == checker.events.healthy
                <span class="comment">-- target changed state, or was added
</span>                ngx.<span class="function-name">log</span>(ngx.DEBUG,<span class="string">"Target switched to healthy: "</span>,
                    target.ip, <span class="string">":"</span>, target.port, <span class="string">" "</span>, target.hostname)
            <span class="keyword">elseif</span> eventname ==  checker.events.unhealthy
                <span class="comment">-- target changed state, or was added
</span>                ngx.<span class="function-name">log</span>(ngx.DEBUG,<span class="string">"Target switched to unhealthy: "</span>,
                    target.ip, <span class="string">":"</span>, target.port, <span class="string">" "</span>, target.hostname)
            <span class="keyword">else</span>
                <span class="comment">-- unknown event
</span>            <span class="keyword">end</span>
        <span class="keyword">end</span>
    }
}
</pre>


<p><a name="Description"></a></p>
<h2>Description</h2>

<p>This library supports performing active and passive health checks on arbitrary hosts.</p>

<p>Control of the library happens via its programmatic API. Consumption of its events
happens via the <a href="https://github.com/Kong/lua-resty-worker-events">lua-resty-worker-events</a> library.</p>

<p>Targets are added using <code>checker:add_target(host, port)</code>.
Changes in status ("healthy" or "unhealthy") are broadcasted via worker-events.</p>

<p>Active checks are executed in the background based on the specified timer intervals.</p>

<p>For passive health checks, the library receives explicit notifications via its
programmatic API using functions such as <code>checker:report_http_status(host, port, status)</code>.</p>

<p>See the <a href="http://kong.github.io/lua-resty-healthcheck">online LDoc documentation</a>
for the complete API.</p>

<p><a name="History"></a></p>
<h2>History</h2>

<p>Versioning is strictly based on <a href="https://semver.org/">Semantic Versioning</a></p>

<h3>Releasing new versions:</h3>

<ul>
    <li>update changelog below (PR's should be merged including a changelog entry)</li>
    <li>based on changelog determine new SemVer version</li>
    <li>create a new rockspec</li>
    <li>render the docs using <code>ldoc</code> (don't do this within PR's)</li>
    <li>commit as "release x.x.x" (do not include rockspec revision)</li>
    <li>tag the commit with "x.x.x" (do not include rockspec revision)</li>
    <li>push commit and tag</li>
    <li>upload rock to luarocks: <code>luarocks upload rockspecs/[name] --api-key=abc</code></li>
</ul>

<h3>3.1.1 (19-Nov-2025)</h3>

<ul>
    <li>Fix: change default headers to empty table instead of an array to remove deprecation notice <a href="https://github.com/Kong/lua-resty-healthcheck/pull/174">#174</a></li>
</ul>


<h3>3.1.0 (19-Jun-2024)</h3>

<ul>
    <li>Feat: remove version check of resty.events <a href="https://github.com/Kong/lua-resty-healthcheck/pull/162">#162</a></li>
</ul>

<h3>3.0.2 (16-May-2024)</h3>

<ul>
    <li>Fix: avoid creating multiple timers to run the same active check <a href="https://github.com/Kong/lua-resty-healthcheck/pull/157">#157</a></li>
</ul>

<h3>3.0.1 (22-Dec-2023)</h3>

<ul>
    <li>Fix: fix delay clean logic when multiple healthchecker was started <a href="https://github.com/Kong/lua-resty-healthcheck/pull/146">#146</a></li>
</ul>

<h3>3.0.0 (12-Oct-2023)</h3>

<ul>
    <li>Perf: optimize by localizing some functions <a href="https://github.com/Kong/lua-resty-healthcheck/pull/92">#92</a> (backport)</li>
    <li>Fix: Generate fresh default http_statuses within new() <a href="https://github.com/Kong/lua-resty-healthcheck/pull/83">#83</a> (backport)</li>
</ul>

<h3>2.0.0 (22-Sep-2020)</h3>

<p><strong>Note:</strong>
Changes in this version has been discarded from current &amp; future development.
Below you can see it's changelog but be aware that these changes might not be present in <code>3.y.z</code> unless they are explicitly stated in <code>3.y.z</code>, <code>1.6.3</code> or previous releases. Read more at: <a href="https://github.com/Kong/lua-resty-healthcheck/pull/142">release 3.0.0 (#142)</a> and <a href="https://github.com/Kong/lua-resty-healthcheck/pull/144">chore(*): realign master branch to 3.0.0 release (#144)</a></p>

<blockquote>
    <ul>
        <li>BREAKING: fallback for deprecated top-level field <a href="https://www.lua.org/manual/5.1/manual.html#pdf-type">type</a> is now removed
        (deprecated since <code>0.5.0</code>) <a href="https://github.com/Kong/lua-resty-healthcheck/pull/56">#56</a></li>
        <li>BREAKING: Bump <code>lua-resty-worker-events</code> dependency to <code>2.0.0</code>. This makes
        a lot of the APIs in this library asynchronous as the worker events <code>post</code>
        and <code>post_local</code> won't anymore call <code>poll</code> on a running worker automatically,
        for more information, see:
        https://github.com/Kong/lua-resty-worker-events#200-16-september-2020</li>
        <li>BREAKING: tcp<em>failures can no longer be 0 on http(s) checks (unless http(s)</em>failures
        are also set to 0) <a href="https://github.com/Kong/lua-resty-healthcheck/pull/55">#55</a></li>
        <li>feature: Added support for https_sni <a href="https://github.com/Kong/lua-resty-healthcheck/pull/49">#49</a></li>
        <li>fix: properly log line numbers by using tail calls <a href="https://github.com/Kong/lua-resty-healthcheck/pull/29">#29</a></li>
        <li>fix: when not providing a hostname, use IP <a href="https://github.com/Kong/lua-resty-healthcheck/pull/48">#48</a></li>
        <li>fix: makefile; make install</li>
        <li>feature: added a status version field <a href="https://github.com/Kong/lua-resty-healthcheck/pull/54">#54</a></li>
        <li>feature: add headers for probe request <a href="https://github.com/Kong/lua-resty-healthcheck/pull/54">#54</a></li>
        <li>fix: exit early when reloading during a probe <a href="https://github.com/Kong/lua-resty-healthcheck/pull/47">#47</a></li>
        <li>fix: prevent target-list from being nil, due to async behaviour <a href="https://github.com/Kong/lua-resty-healthcheck/pull/44">#44</a></li>
        <li>fix: replace timer and node-wide locks with resty-timer, to prevent interval
        skips <a href="https://github.com/Kong/lua-resty-healthcheck/pull/59">#59</a></li>
        <li>change: added additional logging on posting events <a href="https://github.com/Kong/lua-resty-healthcheck/issues/25">#25</a></li>
        <li>fix: do not run out of timers during init/init_worker when adding a vast
        amount of targets <a href="https://github.com/Kong/lua-resty-healthcheck/pull/57">#57</a></li>
        <li>fix: do not call on the module table, but use a method for locks. Also in
        <a href="https://github.com/Kong/lua-resty-healthcheck/pull/57">#57</a></li>
    </ul>
</blockquote>


<h3>1.6.3 (06-Sep-2023)</h3>

<ul>
    <li>Feature: Added support for https_sni <a href="https://github.com/Kong/lua-resty-healthcheck/pull/49">#49</a> (backport)</li>
    <li>Fix: Use OpenResty API for mTLS <a href="https://github.com/Kong/lua-resty-healthcheck/pull/99">#99</a> (backport)</li>
</ul>

<h3>1.6.2 (17-Nov-2022)</h3>

<ul>
    <li>Fix: avoid raising worker events for new targets that were marked for delayed
    removal, i.e. targets that already exist in memory only need the removal flag
    cleared when added back. <a href="https://github.com/Kong/lua-resty-healthcheck/pull/122">#122</a></li>
</ul>

<h3>1.6.1 (25-Jul-2022)</h3>

<ul>
    <li>Fix: improvements to ensure the proper securing of shared resources to avoid
    race conditions and clearly report failure states.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/112">#112</a>,
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/113">#113</a>,
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/114">#114</a>.</li>
    <li>Fix: reduce the frequency of checking for unused targets, reducing the number
    of locks created. <a href="https://github.com/Kong/lua-resty-healthcheck/pull/116">#116</a></li>
    <li>Fix accept any <a href="https://github.com/Kong/lua-resty-events">lua-resty-events</a>
    <code>0.1.x</code> release. <a href="https://github.com/Kong/lua-resty-healthcheck/pull/118">#118</a></li>
</ul>

<h3>1.6.0 (27-Jun-2022)</h3>

<ul>
    <li>Feature: introduce support to <a href="https://github.com/Kong/lua-resty-events">lua-resty-events</a>
    module in addition to <a href="https://github.com/Kong/lua-resty-worker-events">lua-resty-worker-events</a>
    support. With this addition, the lua-resty-healthcheck luarocks package does
    not require a specific event-sharing module anymore, but you are still
    required to provide either lua-resty-worker-events or lua-resty-events.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/105">#105</a></li>
    <li>Change: if available, lua-resty-healthcheck now uses <code>string.buffer</code>, the new LuaJIT's
    serialization API. If it is unavailable, lua-resty-healthcheck fallbacks to
    cjson.  <a href="https://github.com/Kong/lua-resty-healthcheck/pull/109">#109</a></li>
</ul>

<h3>1.5.3 (14-Nov-2022)</h3>

<ul>
    <li>Fix: avoid raising worker events for new targets that were marked for delayed
    removal, i.e. targets that already exist in memory only need the removal flag
    cleared when added back. <a href="https://github.com/Kong/lua-resty-healthcheck/pull/121">#121</a></li>
</ul>

<h3>1.5.2 (07-Jul-2022)</h3>

<ul>
    <li>Better handling of <code>resty.lock</code> failure modes, adding more checks to ensure the
    lock is held before running critical code, and improving the decision whether a
    function should be retried after a timeout trying to acquire a lock.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/113">#113</a></li>
    <li>Increased logging for locked function failures.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/114">#114</a></li>
    <li>The cleanup frequency of deleted targets was lowered, cutting the number of
    created locks in a short period.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/116">#116</a></li>
</ul>

<h3>1.5.1 (23-Mar-2022)</h3>

<ul>
    <li>Fix: avoid breaking active health checks when adding or removing targets.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/93">#93</a></li>
</ul>

<h3>1.5.0 (09-Feb-2022)</h3>

<ul>
    <li>New option <code>checks.active.headers</code> supports one or more lists of values indexed by
    header name. <a href="https://github.com/Kong/lua-resty-healthcheck/pull/87">#87</a></li>
    <li>Introduce dealyed_clear() function, used to remove addresses after a time interval.
    This function may be used when an address is being removed but may be added again
    before the interval expires, keeping its health status.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/88">#88</a></li>
</ul>

<h3>1.4.3 (31-Mar-2022)</h3>

<ul>
    <li>Fix: avoid breaking active health checks when adding or removing targets.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/100">#100</a></li>
</ul>

<h3>1.4.2 (29-Jun-2021)</h3>

<ul>
    <li>Fix: prevent new active checks being scheduled while a health check is running.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/72">#72</a></li>
    <li>Fix: remove event watcher when stopping an active health check.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/74">#74</a>; fixes Kong issue
    <a href="https://github.com/Kong/kong/issues/7406">#7406</a></li>
</ul>

<h3>1.4.1 (17-Feb-2021)</h3>

<ul>
    <li>Fix: make sure that a single worker will actively check hosts' statuses.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/67">#67</a></li>
</ul>

<h3>1.4.0 (07-Jan-2021)</h3>

<ul>
    <li>Use a single timer to actively health check targets. This reduces the number
    of timers used by health checkers, as they used to use two timers by each
    target. <a href="https://github.com/Kong/lua-resty-healthcheck/pull/62">#62</a></li>
</ul>

<h3>1.3.0 (17-Jun-2020)</h3>

<ul>
    <li>Adds support to mTLS to active healthchecks. This feature  can be used adding
    the fields <code>ssl_cert</code> and <code>ssl_key</code>, with certificate and key respectively,
    when creating a new healthcheck object.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/41">#41</a></li>
</ul>

<h3>1.2.0 (13-Feb-2020)</h3>

<ul>
    <li>Adds <a href="../index.html#checker:set_all_target_statuses_for_hostname">set_all_target_statuses_for_hostname</a>, which sets the targets for
    all entries with a given hostname at once.</li>
</ul>

<h3>1.1.2 (19-Dec-2019)</h3>

<ul>
    <li>Fix: when <code>ngx.sleep</code> API is not available (e.g. in the log phase) it is not
    possible to lock using lua-resty-lock and any function that needs exclusive
    access would fail. This fix adds a retry method that starts a new light
    thread, which has access to <code>ngx.sleep</code>, to lock the critical path.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/37">#37</a>;</li>
</ul>

<h3>1.1.1 (14-Nov-2019)</h3>

<ul>
    <li>Fix: fail when it is not possible to get exclusive access to the list of
    targets. This fix prevents that workers get to an inconsistent state.
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/34">#34</a>;</li>
</ul>

<h3>1.1.0 (30-Sep-2019)</h3>

<ul>
    <li>Add support for setting the custom <code>Host</code> header to be used for active checks.</li>
    <li>Fix: log error on SSL Handshake failure
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/28">#28</a>;</li>
</ul>

<h3>1.0.0 (05-Jul-2019)</h3>

<ul>
    <li>BREAKING: all API functions related to hosts require a <code>hostname</code> argument
    now. This way different hostnames listening on the same IP and ports
    combination do not have an effect on each other.</li>
    <li>Fix: fix reporting active TCP probe successes
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/20">#20</a>;
    fixes issue <a href="https://github.com/Kong/lua-resty-healthcheck/issues/19">#19</a></li>
</ul>

<h3>0.6.1 (04-Apr-2019)</h3>

<ul>
    <li>Fix: set up event callback only after target list is loaded
    <a href="https://github.com/Kong/lua-resty-healthcheck/pull/18">#18</a>;
    fixes Kong issue <a href="https://github.com/Kong/kong/issues/4453">#4453</a></li>
</ul>

<h3>0.6.0 (26-Sep-2018)</h3>

<ul>
    <li>Introduce <code>checks.active.https_verify_certificate</code> field.
    It is <code>true</code> by default; setting it to <code>false</code> disables certificate
    verification in active healthchecks over HTTPS.</li>
</ul>

<h3>0.5.0 (25-Jul-2018)</h3>

<ul>
    <li>Add support for <code>https</code> -- thanks @gaetanfl for the PR!</li>
    <li>Introduce separate <code>checks.active.type</code> and <code>checks.passive.type</code> fields;
    the top-level <a href="https://www.lua.org/manual/5.1/manual.html#pdf-type">type</a> field is still supported as a fallback but is now
    deprecated.</li>
</ul>

<h3>0.4.2 (23-May-2018)</h3>

<ul>
    <li>Fix <code>Host</code> header in active healthchecks</li>
</ul>

<h3>0.4.1 (21-May-2018)</h3>

<ul>
    <li>Fix internal management of healthcheck counters</li>
</ul>

<h3>0.4.0 (20-Mar-2018)</h3>

<ul>
    <li>Correct setting of defaults in <code>http_statuses</code></li>
    <li>Type and bounds checking to <code>checks</code> table</li>
</ul>

<h3>0.3.0 (18-Dec-2017)</h3>

<ul>
    <li>Disable individual checks by setting their counters to 0</li>
</ul>

<h3>0.2.0 (30-Nov-2017)</h3>

<ul>
    <li>Adds <a href="../index.html#checker:set_target_status">set_target_status</a></li>
</ul>

<h3>0.1.0 (27-Nov-2017) Initial release</h3>

<ul>
    <li>Initial upload</li>
</ul>

<p><a name="Copyright_and_License"></a></p>
<h2>Copyright and License</h2>

<pre><code> Copyright 2017-2022 Kong Inc.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
</code></pre>




</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
<i style="float:right;">Last updated 2025-11-19 15:24:06 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
